home *** CD-ROM | disk | FTP | other *** search
/ Best Tools for JAVA / Best Tools for JAVA.iso / JAVA_ALL / IDE / SUBARTIC / SUB_ARCT / INPUT / TEXT_ACC.JAV < prev    next >
Encoding:
Text File  |  1996-10-04  |  8.3 KB  |  183 lines
  1.  
  2. package sub_arctic.input;
  3.  
  4. /** 
  5.  * Input protocol for objects that accept textual input.  This protocol is
  6.  * dispatched by the text focus agent.  In addition to simple text input
  7.  * this protocol provides features for filtering characters, recognizing
  8.  * and acting of special "action characters", and performing standard 
  9.  * edit functions (i.e., character delete and line kill).
  10.  *
  11.  * @see sub_arctic.input.text_focus_agent
  12.  * @author Scott Hudson
  13.  */
  14. public interface text_acceptor extends focusable {
  15.  
  16.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  17.  
  18.   /** 
  19.    * indicate that this object is the new text focus and will receive 
  20.    * subsequent text input.  
  21.    *
  22.    * @param event  evt       the event that "caused" the start of text input.
  23.    * @param Object user_info the user info associated with this object when it
  24.    *                         was added to the focus set.
  25.    * @returns boolean indicating if this input was consumed.
  26.    */
  27.   public boolean start_text_entry(event evt, Object user_info);
  28.  
  29.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  30.  
  31.   /** 
  32.    * Prefilter a character before providing it as input.  This routine gets 
  33.    * called to allow the object to modify the character before it is passed 
  34.    * to new_char().  Input to the method is the ordinal value of the input 
  35.    * character in question along with the modifier mask associated with it.  
  36.    * Output should either be the ordinal value of a  character or a specific
  37.    * negative value signifying one of several special actions.  This routine
  38.    * can be used to do a translation (e.g. to all lower case) or to filter 
  39.    * out unwanted characters (e.g. everything except decimal digits). <p>
  40.    * 
  41.    * Filtering is done by returning the special value DISCARD_CHAR (= -1),
  42.    * which signifies that the character is not to be passed to new_char().
  43.    * Translation is done by returning the ordinal value of the translated
  44.    * character.  In addition, the value CLOSURE_ACTION_CHAR (= -2) can be 
  45.    * returned to indicate that the action_char() method should be invoked 
  46.    * instead of new_char().  This is typically done for end of line 
  47.    * characters that signify completion of an entry.<p.
  48.    * 
  49.    * All modifications to the character are considered local to this object 
  50.    * and do not change how the character might be delivered to another object.
  51.    * This routine is not called for cursor movement or other special keys 
  52.    * (which are dispatched with special_key()), or characters classified as 
  53.    * edit keys (e.g. to delete a character or line).  The text input dispatch 
  54.    * agent class (text_focus_agent) provides several standard filters that 
  55.    * can be  called for common operations.
  56.    *
  57.    * @see sub_arctic.input.text_focus_agent
  58.    * @see sub_arctic.input.event
  59.    * @param int input_char ordinal value of the original input character.
  60.    * @param int modifiers modifier mask (see event for encoding).
  61.    * @return int the ordinal value of the translated character, or one of the
  62.    *             special (negative) values DISCARD_CHAR or CLOSURE_ACTION_CHAR.
  63.    */
  64.   public int char_filter(int input_char, int modifiers);
  65.  
  66.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  67.  
  68.   /** 
  69.    * Constant for return from char_filter signifying that character is to 
  70.    * be discarded.
  71.    */
  72.   public static final int DISCARD_CHAR = -1;
  73.  
  74.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  75.  
  76.   /** 
  77.    * Constant for return from char_filter to signify that character is to 
  78.    * be considered a closure point which ends input and should be acted upon
  79.    * (usually this would be done for end of line characters).
  80.    */
  81.   public static final int CLOSURE_ACTION_CHAR = -2;
  82.  
  83.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  84.  
  85.   /** 
  86.    * Provide input for a single character.  
  87.    *
  88.    * @param event  evt       the original event for the character input.
  89.    * @param char   ch        the translated character that should be 
  90.    *                         considered the actual input.
  91.    * @param Object user_info the user info that was associated with this object
  92.    *                         when it was established as a text focus.
  93.    */
  94.   public boolean new_char(event evt, char ch, Object user_info);
  95.  
  96.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  97.  
  98.   /** 
  99.    * Provide input for a character that has been classified as a closure
  100.    * action (by returning CLOSURE_ACTION_CHAR from char_filter).  
  101.    *
  102.    * @param event  evt       the original event for the character input.
  103.    * @param char   ch        the character.
  104.    * @param Object user_info the user info that was associated with this object
  105.    *                         when it was established as a text focus.
  106.    */
  107.   public boolean action_char(event evt, char ch, Object user_info);
  108.  
  109.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  110.  
  111.   /** 
  112.    * Provide input for a character signifying a delete.  Returns true if the
  113.    * object consumes the input.  Currently, by default if either a backspace 
  114.    * or a delete character is seen, it will be treated as a delete character.
  115.    * This behavior can be changed via the text input dispatch agent.
  116.    * (Unfortunately, AWT does not currently provide a way to determine the 
  117.    * user's edit character preferences, so this is the best we can do.)
  118.    *
  119.    * @param event  evt       the event for the input.
  120.    * @param Object user_info the user info that was associated with this object
  121.    *                         when it was established as a text focus.
  122.    */
  123.   public boolean delete_char(event evt, Object user_info);
  124.  
  125.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  126.  
  127.   /** Provide input for a character signifying a line kill.  Returns true if
  128.    *  the object consumes the input.  Currently a ^U ('\025') is treated as
  129.    *  a line kill. This behavior can be changed via the text input dispatch 
  130.    *  agent. (Unfortunately, AWT does not currently provide a way to determine 
  131.    *  the user's edit character preferences, so this is the best we can do.)
  132.    *
  133.    * @param event  evt       the event for the input.
  134.    * @param Object user_info the user info that was associated with this object
  135.    *                         when it was established as a text focus.
  136.    */
  137.   public boolean line_kill(event evt, Object user_info); 
  138.  
  139.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  140.  
  141.   /** Provide input for a key press signifying a special key (corresponding
  142.    *  to KEY_ACTION events).  Values passed here are from the key field of the
  143.    *  events.  These include: DOWN, END, F1, ..., F12, HOME, LEFT, PGDN, PGUP, 
  144.    *  RIGHT, and UP.  Returns true if the object consumes the event.
  145.    *
  146.    * @see sub_arctic.input.event
  147.    * @param event  evt       the original event for the character input.
  148.    * @param int    key_code  the key code for the action key (see event).
  149.    * @param Object user_info the user info that was associated with this object
  150.    *                         when it was established as a text focus.
  151.    */
  152.   public boolean special_key(event evt, int key_code, Object user_info);
  153.  
  154.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  155.  
  156.   /** Provide input indicating that text input is over (e.g. the text focus
  157.    *  has moved elsewhere.  
  158.    *
  159.    * @param event  evt       the event "causing" this input.
  160.    * @param Object user_info the user info that was associated with this object
  161.    *                         when it was established as a text focus.
  162.    */
  163.   public boolean end_text_entry(event evt, Object  user_info); 
  164.  
  165.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  166. }
  167. /*=========================== COPYRIGHT NOTICE ===========================
  168.  
  169. This file is part of the subArctic user interface toolkit.
  170.  
  171. Copyright (c) 1996 Scott Hudson and Ian Smith
  172. All rights reserved.
  173.  
  174. The subArctic system is freely available for most uses under the terms
  175. and conditions described in 
  176.   http://www.cc.gatech.edu/gvu/ui/sub_arctic/sub_arctic/doc/usage.html 
  177. and appearing in full in the lib/interactor.java source file.
  178.  
  179. The current release and additional information about this software can be 
  180. found starting at: http://www.cc.gatech.edu/gvu/ui/sub_arctic/
  181.  
  182. ========================================================================*/
  183.